User Guide

In this guide, we introduce how to use JSON Forms in Itential Automation Platform (IAP) by providing a walk-through of how to navigate and use the Form Builder application. There are two main components to the JSON Forms application that enable management of forms, a form collection and form builder page. These forms can be used throughout IAP. At a high level, this is achieved by the JSON Forms builder providing the functionality to generate a JSON Schema representation of a form via a drag and drop user interface.

Accessing JSON Forms

JSON forms currently are not part of any application. To access JSON forms, use the API route 'json-forms'.

For example: https://localhost:3443/json-forms

Collection Page

All forms created are displayed in a card grid on the collection page, including previously created forms.

The following actions can be taken from the collection page:

• Create a form.
• Delete an existing form.
• Navigate to the Form Builder to edit an existing form.
• Export/import forms to and from JSON files.
• Sort forms inside the card grid.

Create a New Form

1. Click the plus icon to open the Create New Form card.
2. Enter a form name (required) and a description (optional).
3. Click Save.

Delete an Existing Form

Using the Card Menu

• Click the stacked dots icon to display more options inside of a card.
• Click Delete to delete the form.

Note: You can also use the top menu bar within Form Builder.

Using Multi-Select

• Click the select icon to mark the form as selected.
• Click the delete icon to delete all selected forms.
• Click the unselect icon to unselect all selected forms.

Navigate to Form Builder to Edit Forms

Using Sidebar Navigation

• From the sidebar, click any form in the list to navigate to the Form Builder for that particular form.
• The cards icon (upper-right corner) will direct you to the Home page.

Using the Card Menu

• Click the stacked dots icon to display more options inside of a card.
• Click Edit to make changes to a form.

Export Forms to JSON Files

Using Multi-Select

• Click the select icon to mark the form as selected.
• Click the stacked dots icon in the toolbar to display import/export options.
• Click the Export menu option to export all selected forms to JSON files.

Using the Card Menu

• Click the stacked dots icon to display more options inside of a card.
• Click the Export menu option to download a JSON file representation of the form.

Import Forms from JSON Files

• Click the stacked dots icon in the toolbar to display import/export options.
• Click the Import menu option to import forms from previously exported forms. One or more forms can be imported at a time.

Clone a Form

Using the Card Menu

• Click the stacked dots icon to display more options inside of a card.
• Click the Clone menu option to create a copy of the form.

Note: You can also use the top menu bar within Form Builder.

Preview a Form

Using the Card Menu

• Click the stacked dots icon to display more options inside of a card.
• Click the Preview menu option to show a preview of the form.

Sort Forms

• Click the sort icon in the toolbar to modify the sort options.
• Use the dropdown to change the property the sort is performed on.
• Use the Ascending and Descending radio buttons to change the sort order.

Working with Form Builder

In Form Builder it is possible to change the structure and element composition of previously created forms. From the Form Builder screen you can update a form name, add new form elements, change existing form elements, restructure a form through drag and drop reordering, and inspect different types of form previews.

The following section provides an overview of how to build and edit a JSON form.

Available Elements

The element bin is on the right side of the form builder. There you can find all available elements that can be added to a form.

Layout Elements

Layout elements are not used to directly provide an input field, but rather to group elements or provide unique data structures. There are two types of Layout Elements:

• Containers store form elements to build logical groupings of related form elements. These sub-elements are rendered vertically.
• Tables store form elements to build repeatable groupings of related form elements. Each element added to a table becomes a column in the table. Once the form is rendered, tables allow rows to be added that are made up of these sub-elements for capturing data.

Form Elements

Form elements are used to provide fields that capture values on input. There are five types of Form Elements:

• Text Input — Used to capture short string values.
• Text Area — Used to capture long string values.
• Number Input — Used to capture integer or decimal values.
• Checkbox — Used to capture boolean values.
• Dropdown — Used to capture strings from a set of options.

View and Update Form Details

Update the Form Name or Description

Click the gear icon in the top bar of the Form Builder to open form details. This drawer displays information about who created the form and when, along with who last updated the form and when. From the form details screen, the form name and description can be changed.

Using the Form Builder Canvas

The Form Builder canvas is where the form is built by dragging elements onto the "Drop elements here" zone. As the form is being built, it can be previewed and the generated form schemas can be inspected.

Add Elements to a Form

Layout and form elements can be added to a form by dragging the available elements from the element bin onto the form canvas. For example, to add a text field to a form, drag-and-drop the element labeled Text Input.

Change an Element's properties

Each form element can be edited by clicking its gear icon . This will open the available properties for editing a form element. Below is a list of available properties currently supported for each form element. To update the name of a layout element, edit the text field next to the Container/Table label.

Element	Properties
Text Field	Label, Placeholder, Description, Required, Pattern Validation, Dynamic Validation
Text Area	Label, Placeholder, Description, Required, Pattern Validation, Dynamic Validation
Number Field	Label, Placeholder, Description, Required, Dynamic Validation
Checkbox	Label, Description, Checked
Dropdown	Label, Placeholder, Description, Required, Static Options, Dynamic Options, Pattern Validation, Dynamic Validation

Property	Description
Label	The name of the field.
Placeholder	A user prompt or hint usually displayed inside of the input field before data is entered.
Description	A short description of the field. This displays below the field label.
Static Options	A list of static values to be used as options for dropdowns.
Dynamic Options	Used to retrieve a list of dynamic values through an HTTP request by providing a specific configuration to setup data binding via a request and a value mapping.
Checked	When set to yes, this defaults the value of a checkbox to true.
Required	A value input is required.
Pattern Validation	A regular expression used to validate an input value.
Dynamic Validation	Used to validate an input value through an HTTP request by providing a specific configuration to setup a data binding via a request and a value mapping.

Adding Dropdown Options

There are two methods of adding dropdown options, static and dynamic.

Static Options

To add static options for a dropdown, set the options type to static. Click the + Option button to add items to the draggable list and use the input field to change the value of the dropdown option. Use the drag handle icon to reorganize the list items via drag and drop. Use the delete item icon to remove an item from the dropdown options.

Dynamic Options

To utilize dynamic options for a dropdown, the following fields have to be configured.

Property	Description
Method	The request method.
Request Body	The request body in the form of JSON.
Base URL	The request scheme/protocol + authority + optional port.
API Route	The request path + optional query.
Source Property	A property on the response that contains the array to use as the dropdown options.
Property Key	A property that exists for each of the objects within the array selected on the source property that will become the value of the dropdown options.

The fields configure the HTTP request and the data mapping that will occur when the form is rendered. Follow these steps to configure the request:

1. Select a Method. If POST is selected, then the Request Body field requires input.
2. Input the Base URL.
3. Input the API Route.
4. Hit the play icon button (in Step 1: Request Configuration) to view the response from the request.
5. Select the Source Property.
6. Select the Property Key.
7. Hit the play icon button (in Step 2: Source To Target Mapping) to see a preview of the values that will populate as the dropdown's options.

Adding Validation

There are two methods of adding validation, pattern and dynamic. These can be used together or independently. Both can be added by clicking the + Validation button on field editors, where this option is enabled.

Pattern Validation

To add a pattern validation input a regular expression into the text field labeled Pattern.

Dynamic Validation

To utilize dynamic validation, the following fields have to be configured.

Property	Description
Method	The request method.
Request Body	The request body in the form of JSON.
Base URL	The request scheme/protocol + authority + optional port.
API Route	The request path + optional query.
Source Property	A property on the response that contains boolean value telling if the field value is valid. Currently, only truthy properties are support, meaning isValid will work, but isInvalid will not.
Dynamic Request Body Property	A property on the request body.
Error Message	The error message for when the input value is not valid.

The fields configure the HTTP request and the data mapping that will occur when the form is rendered. Follow these steps to configure the request:

1. Select POST Method and input the Request Body. The Request Body is a mock body for when the request is actually made on during form field input.
2. Input the Base URL.
3. Input the API Route.
4. Hit the play icon button (in Step 1: Request Configuration) to see the response from the request.
5. Select the Source Property.
6. Hit the play icon button (in Step 2: Source To Target Mapping) to see a preview of the boolean value that determines a valid input value.
7. Select the Dynamic Request Body Property (in Step 3: Validation Configuration) to pick which request body property will have its value replaced by the input value being validated.
8. Input the Error Message that is displayed when the input value is invalid.

Reorder Elements

Any form element can be reordered by dragging it from its original location to a new location and dropping it.

Delete Elements

Click the trash can button (top-right corner) to delete an element from the form.

Save Form Changes

Click the Save button to capture any changes made to a form.

Preview a Form

As a form is being built, the form can be previewed by clicking the eye icon in the footer of the Form Builder canvas card.

Inspect the Generated Schemas

To evaluate the underlying data structures that are generated as a form is built, click the code icon button in the footer of the Form Builder canvas card. This displays the JSON Schema, UI Schema, Binding Schema and Validation Schema for the form.